﻿<?xml version="1.0" encoding="utf-8" ?>

<helpItems xmlns="http://msh" schema="maml">

  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
    <command:details>
      <command:name>
        Run-Gallio
      </command:name>
      <maml:description>
        <maml:para>Runs tests using Gallio.</maml:para>
      </maml:description>
      <maml:copyright>
        <maml:para>Copyright © 2005-2009 Gallio Project - http://www.gallio.org/</maml:para>
      </maml:copyright>
      <command:verb>Run</command:verb>
      <command:noun>Gallio</command:noun>
      <dev:version></dev:version>
    </command:details>
    <maml:description>
      <maml:para>The Run-Gallio cmdlet runs tests using Gallio.</maml:para>
    </maml:description>
    <command:syntax>

      <!-- 
      
      Description of the properties used in the command:parameter elements:
      
      #  Required
          * If true, the parameter must appear in all commands that use the parameter set.
          * If false, the parameter is optional in all commands that use the parameter set.

      # Position
          * If named, the parameter name is required.
          * If positional, the parameter name is optional. When it is omitted, the parameter value must be in the specified position in the command. For example, if the value is position="1", the parameter value must be the first or only unnamed parameter value in the command.

      # Pipeline Input
          * If true (ByValue), you can pipe input to the parameter. The input is associated with ("bound to") the parameter even if the property name and the object type do not match the expected type. The Microsoft® Windows® PowerShell parameter binding components try to convert the input to the correct type and fail the command only when the type cannot be converted. Only one parameter in a parameter set can be associated by value.
          * If true (ByPropertyName), you can pipe input to the parameter. However, the input is associated with the parameter only when the parameter name matches the name of a property of the input object. For example, if the parameter name is Path, objects piped to the cmdlet are associated with that parameter only when the object has a property named path.
          * If true (ByValue, ByPropertyName), you can pipe input to the parameter either by property name or by value. Only one parameter in a parameter set can be associated by value.
          * If false, you cannot pipe input to this parameter.

      # Globbing
          * If true, the text that the user types for the parameter value can include wildcard characters.
          * If false, the text that the user types for the parameter value cannot include wildcard characters.

      # VariableLength
      
          * It looks this property is meaningless, at least in PowerShell 1.0:
          
          ============================================================================
          Hi Keith

          This attribute is not consumed by our Help formatter in the current release.
          This is added to comply with MAML command schema.

          Thanks
          Krishna[MSFT]
          Windows PowerShell Team
          Microsoft Corporation
          This posting is provided "AS IS" with no warranties, and confers no rights.
          ============================================================================      
      -->
      
      <command:syntaxItem>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>ApplicationBaseDirectory</maml:name>
          <maml:description>
            <maml:para>The relative or absolute path of the application base directory to use during test execution instead of the default.</maml:para>
          </maml:description>
          <dev:defaultValue>String.Empty</dev:defaultValue>
        </command:parameter>
        
        <maml:name>Run-Gallio</maml:name>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1">
          <maml:name>Files</maml:name>
          <maml:description>
            <maml:para>The list of comma-separated, relative or absolute paths of test files, projects and assemblies to execute.  Wildcards may be used.</maml:para>
          </maml:description>
        </command:parameter>
        
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>DoNotRun</maml:name>
          <maml:description>
            <maml:para>Sets whether to load the tests but not run them. This option may be used to produce a report that contains test metadata for consumption by other tools.</maml:para>
          </maml:description>
          <dev:defaultValue>false</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>Filter</maml:name>
          <maml:description>
            <maml:para>
              Sets the filter set to apply, which consists of a sequence of one or more inclusion
              or exclusion filter rules prefixed using 'include' (optional) or 'exclude'.
              A filter rule consists of zero or more filter expressions
              that may be combined using 'and', 'or', and 'not' and grouped with
              parentheses.  A filter expression consists of a filter key followed by one or
              more comma-delimited matching values in the form 'key: value, "quoted value",
              /regular expression/'.
            </maml:para>
          </maml:description>
          <dev:defaultValue>*</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>HintDirectories</maml:name>
          <maml:description>
            <maml:para>The list of directories used for loading referenced assemblies and other dependent resources.</maml:para>
          </maml:description>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>NoEchoResults</maml:name>
          <maml:description>
            <maml:para>Sets whether to echo results to the screen as tests finish. If this option is specified only the final summary statistics are displayed. Otherwise test results are echoed to the console in varying detail depending on the current verbosity level.</maml:para>
          </maml:description>
          <dev:defaultValue>false</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>NoProgress</maml:name>
          <maml:description>
            <maml:para>Sets whether progress information is shown during the execution. If this option is specified, the execution is silent and no progress information is displayed.</maml:para>
          </maml:description>
          <dev:defaultValue>false</dev:defaultValue>
        </command:parameter>
        
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>PluginDirectories</maml:name>
          <maml:description>
            <maml:para>Additional Gallio plugin directories to search recursively.</maml:para>
          </maml:description>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>ReportDirectory</maml:name>
          <maml:description>
            <maml:para>Sets the name of the directory where the reports will be put.</maml:para>
          </maml:description>
          <dev:defaultValue>"Reports"</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>ReportNameFormat</maml:name>
          <maml:description>
            <maml:para>Sets the format string to use to generate the reports filenames.</maml:para>
          </maml:description>
          <dev:defaultValue>test-report-{0}-{1}</dev:defaultValue>          
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>ReportTypes</maml:name>
          <maml:description>
            <maml:para>A list of the types of reports to generate, separated by semicolons.</maml:para>
          </maml:description>
          <dev:defaultValue>String.Empty</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>RunnerType</maml:name>
          <maml:description>
            <maml:para>Sets the type of test runner to use (LocalAppDomain, IsolatedAppDomain or IsolatedProcess, but more could be available as plugins).</maml:para>
          </maml:description>
          <dev:defaultValue>IsolatedProcess</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>ShadowCopy</maml:name>
          <maml:description>
            <maml:para>
              Enables shadow copying when set to true. Shadow copying allows the original assemblies to be modified while the tests are running. However, shadow copying may occasionally cause some tests to fail if they depend on their original location.
            </maml:para>
          </maml:description>
          <dev:defaultValue>false</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>DebugTests</maml:name>
          <maml:description>
            <maml:para>
              Attaches the debugger to the test process.
            </maml:para>
          </maml:description>
          <dev:defaultValue>false</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>ShowReports</maml:name>
          <maml:description>
            <maml:para>Sets whether to open the generated reports once execution has finished.</maml:para>
          </maml:description>
          <dev:defaultValue>false</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>WorkingDirectory</maml:name>
          <maml:description>
            <maml:para>
              The relative or absolute path of the working directory to use during test execution instead of the default.
            </maml:para>
          </maml:description>
          <dev:defaultValue>String.Empty</dev:defaultValue>
        </command:parameter>

        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
          <maml:name>RuntimeVersion</maml:name>
          <maml:description>
            <maml:para>The version of the .Net runtime to use for running tests.  For the CLR, this must be the name of one of the framework directories in %SystemRoot%\Microsoft.Net\Framework.  eg. 'v2.0.50727'.  The default is null which uses the most recent installed and supported framework.</maml:para>
          </maml:description>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>

    <command:parameters>

      <!-- This section is a copy paste of the syntax parameter. The only difference between both sections
      is that here the parameters can appear only once, whereas in the syntax section they can appear in
      different parameter sets. -->
      
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>ApplicationBaseDirectory</maml:name>
        <maml:description>
          <maml:para>The relative or absolute path of the application base directory.</maml:para>
        </maml:description>
        <dev:defaultValue>String.Empty</dev:defaultValue>
      </command:parameter>

      <maml:name>Run-Gallio</maml:name>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1">
        <maml:name>Files</maml:name>
        <maml:description>
          <maml:para>The list of comma-separated, relative or absolute paths of test files, projects and assemblies to execute.  Wildcards may be used.</maml:para>
        </maml:description>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>DoNotRun</maml:name>
        <maml:description>
          <maml:para>Sets whether to load the tests but not run them. This option may be used to produce a report that contains test metadata for consumption by other tools.</maml:para>
        </maml:description>
        <dev:defaultValue>false</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>Filter</maml:name>
        <maml:description>
          <maml:para>
            Sets the filter set to apply, which consists of a sequence of one or more inclusion
            or exclusion filter rules prefixed using 'include' (optional) or 'exclude'.
            A filter rule consists of zero or more filter expressions
            that may be combined using 'and', 'or', and 'not' and grouped with
            parentheses.  A filter expression consists of a filter key followed by one or
            more comma-delimited matching values in the form 'key: value, "quoted value",
            /regular expression/'.
          </maml:para>
        </maml:description>
        <dev:defaultValue>*</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>HintDirectories</maml:name>
        <maml:description>
          <maml:para>The list of directories used for loading referenced assemblies and other dependent resources.</maml:para>
        </maml:description>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>NoEchoResults</maml:name>
        <maml:description>
          <maml:para>Sets whether to echo results to the screen as tests finish. If this option is specified only the final summary statistics are displayed. Otherwise test results are echoed to the console in varying detail depending on the current verbosity level.</maml:para>
        </maml:description>
        <dev:defaultValue>false</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>NoProgress</maml:name>
        <maml:description>
          <maml:para>Sets whether progress information is shown during the execution. If this option is specified, the execution is silent and no progress information is displayed.</maml:para>
        </maml:description>
        <dev:defaultValue>false</dev:defaultValue>
      </command:parameter>
      
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>PluginDirectories</maml:name>
        <maml:description>
          <maml:para>Additional Gallio plugin directories to search recursively.</maml:para>
        </maml:description>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>ReportDirectory</maml:name>
        <maml:description>
          <maml:para>Sets the name of the directory where the reports will be put.</maml:para>
        </maml:description>
        <dev:defaultValue>"Reports"</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>ReportNameFormat</maml:name>
        <maml:description>
          <maml:para>Sets the format string to use to generate the reports filenames.</maml:para>
        </maml:description>
        <dev:defaultValue>test-report-{0}-{1}</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>ReportTypes</maml:name>
        <maml:description>
          <maml:para>A list of the types of reports to generate, separated by semicolons.</maml:para>
        </maml:description>
        <dev:defaultValue>String.Empty</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>RunnerType</maml:name>
        <maml:description>
          <maml:para>Sets the type of test runner to use: Local, IsolatedAppDomain, IsolatedProcess, or others that may be provided by plugins.</maml:para>
        </maml:description>
        <dev:defaultValue>IsolatedProcess</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>RunnerExtensions</maml:name>
        <maml:description>
          <maml:para>Specifies the type, assembly, and parameters of custom test runner extensions to use during the test run in the form: '[Namespace.]Type,Assembly[;Parameters].  eg. 'FancyLogger,MyExtensions.dll;ColorOutput,FancyIndenting'</maml:para>
        </maml:description>
      </command:parameter>
      
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>ShadowCopy</maml:name>
        <maml:description>
          <maml:para>
            Enables shadow copying when set to true. Shadow copying allows the original assemblies to be modified while the tests are running. However, shadow copying may occasionally cause some tests to fail if they depend on their original location.
          </maml:para>
        </maml:description>
        <dev:defaultValue>false</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>DebugTests</maml:name>
        <maml:description>
          <maml:para>
            Attaches the debugger to the test process.
          </maml:para>
        </maml:description>
        <dev:defaultValue>false</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>ShowReports</maml:name>
        <maml:description>
          <maml:para>Sets whether to open the generated reports once execution has finished.</maml:para>
        </maml:description>
        <dev:defaultValue>false</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>WorkingDirectory</maml:name>
        <maml:description>
          <maml:para>
            The relative or absolute path of the working directory. If relative, the path is based on the current working directory, so a value of "" (an empty string) causes the current working directory to be used.
          </maml:para>
        </maml:description>
        <dev:defaultValue>String.Empty</dev:defaultValue>
      </command:parameter>

      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named">
        <maml:name>RuntimeVersion</maml:name>
        <maml:description>
          <maml:para>The version of the .Net runtime to use for running tests.  For the CLR, this must be the name of one of the framework directories in %SystemRoot%\Microsoft.Net\Framework.  eg. 'v2.0.50727'.  The default is null which uses the most recent installed and supported framework.</maml:para>
        </maml:description>
      </command:parameter>
    </command:parameters>

    <command:examples>
      <command:example>
        # Makes the Gallio commands available
        Add-PSSnapIn Gallio
        # Runs TestAssembly1.dll
        Run-Gallio "[Path-to-assembly1]\TestAssembly1.dll","[Path-to-assembly2]\TestAssembly2.dll","[Path-to-test-script1]/TestScript1_spec.rb","[Path-to-test-script2]/TestScript2.xml" -f Category:UnitTests -rd C:\build\reports -rf html
      </command:example>
    </command:examples>

  </command:command>

</helpItems>
